14. Grails and Spring

This section is for advanced users and those who are interested in how Grails integrates with and builds on the Spring Framework This section is also useful for plug-in developers considering doing runtime configuration Grails.

14.1 The Underpinnings of Grails

Grails is actually a Spring MVC application in disguise. Spring MVC is the Spring framework's built-in MVC web application framework. Although Spring MVC suffers from the same difficulties as frameworks like Struts in terms of its ease of use, it is superbly designed and architected and was, for Grails, the perfect framework to build another framework on top of.

Grails leverages Spring MVC in the following areas:

In other words Grails has Spring embedded running all the way through it.

The Grails ApplicationContext

Spring developers are often keen to understand how the Grails ApplicationContext instance is constructed. The basics of it are as follows.

Configured Spring Beans

Most of Grails' configuration happens at runtime. Each plug-in may configure Spring beans that are registered with the ApplicationContext. For a reference as to which beans are configured refer to the reference guide which describes each of the Grails plug-ins and which beans they configure.

14.2 Configuring Additional Beans

Using XML

Beans can be configured using the grails-app/conf/spring/resources.xml file of your Grails application. This file is typical Spring XML file and the Spring documentation has an excellent reference on how to go about configuration Spring beans. As a trivial example you can configure a bean with the following syntax:

<bean id="myBean" class="my.company.MyBeanImpl"></bean>

Once configured the bean, in this case named myBean, can be auto-wired into most Grails types including controllers, tag libraries, services and so on:

class ExampleController {
     def myBean
}

Referencing Existing Beans

Beans declared in resources.xml can also reference Grails classes by convention. For example if you need a reference to a service such as BookService in your bean you use the property name representation of the class name. In the case of BookService this would be bookService. For example:

<bean id="myBean" class="my.company.MyBeanImpl">
	<property name="bookService" ref="bookService" />	
</bean>

The bean itself would of course need a public setter, which in Groovy is defined like this:

package my.company
class MyBeanImpl {
	BookService bookService
}

or in Java like this:

package my.company;
class MyBeanImpl {
	private BookService bookService;
	public void setBookService(BookService theBookService) {
		this.bookService = theBookService;
	}
}

Since much of Grails configuration is done at runtime by convention many of the beans are not declared anywhere, but can still be referenced inside your Spring configuration. For example if you need a reference to the Grails DataSource you could do:

<bean id="myBean" class="my.company.MyBeanImpl">
	<property name="bookService" ref="bookService" />	
	<property name="dataSource" ref="dataSource" />
</bean>

Or if you need the Hibernate SessionFactory this will work:

<bean id="myBean" class="my.company.MyBeanImpl">
	<property name="bookService" ref="bookService" />	
	<property name="sessionFactory" ref="sessionFactory" />
</bean>

For a full reference of the available beans see the Plug-in reference in the reference guide.

Using the Spring DSL

If you want to use the Spring DSL that Grails provides then you need to create a grails-app/conf/spring/resources.groovy file and define a method call called beans that takes a block:

beans = {
	// beans here
}

The same configuration for the XML example could be represented as:

beans = {
	myBean(my.company.MyBeanImpl) {
		bookService = ref("bookService")
	}	
}

The main advantage of this way is that you can now mix logic in within your bean definitions, for example based on the environment:

import grails.util.*
beans = {
	switch(GrailsUtil.environment) {
		case "production":
			myBean(my.company.MyBeanImpl) {
				bookService = ref("bookService")
			}
		break
		case "development":
			myBean(my.company.mock.MockImpl) {
				bookService = ref("bookService")
			}	
		break
	}	
}

14.3 Runtime Spring with the Beans DSL

Spring is very powerful, but the XML based syntax is very verbose and violates DRY at multiple levels even with the recent additions to Spring 2.0. This Bean builder in Grails aims to provide a simplified way of wiring together dependencies that uses Spring at its core.

In addition, Spring's regular way of configuration (via XML) is essentially static and very difficult to modify and configure at runtime other than programmatic XML creation which is both error prone and verbose. Grails' BeanBuilder changes all that by making it possible to programmatically wire together components at runtime thus allowing you to adapt the logic based on system properties or environment variables.

This enables the code to adapt to its environment and avoids unnecessary duplication of code (having different Spring configs for test, development and production environments)

h4. The BeanBuilder class

Grails provides a grails.spring.BeanBuilder class that uses dynamic Groovy to construct bean definitions. The basics are as follows:

import org.apache.commons.dbcp.BasicDataSource
  import org.codehaus.groovy.grails.orm.hibernate.ConfigurableLocalSessionFactoryBean;
  import org.springframework.context.ApplicationContext;
  def bb = new grails.spring.BeanBuilder()
  bb.beans {
      dataSource(BasicDataSource) {
          driverClassName = "org.hsqldb.jdbcDriver"
          url = "jdbc:hsqldb:mem:grailsDB"
          username = "sa"
          password = ""
      }
      sessionFactory(ConfigurableLocalSessionFactoryBean) {
          dataSource = dataSource
          hibernateProperties = [ "hibernate.hbm2ddl.auto":"create-drop",
                                  "hibernate.show_sql":true  ]
      }
  }
  ApplicationContext appContext = bb.createApplicationContext()

Within plug-ins and the grails-app/conf/spring/resources.groovy file you don't need to create a new instance of BeanBuilder. Instead the DSL is implicitly available inside the doWithSpring and beans blocks respectively.

The above example shows how you would configure Hibernate with an appropriate data source with the BeanBuilder class.

Essentially, each method call (in this case dataSource and sessionFactory calls) map to the name of the bean in Spring. The first argument to the method is the bean's class, whilst the last argument is a block. Within the body of the block you can set properties on the bean using standard Groovy syntax

Bean references are resolved automatically be using the name of the bean. This can be seen in the example above with the way the sessionFactory bean resolves the dataSource reference.

Certain special properties related to bean management can also be set by the builder, as seen in the following code:

sessionFactory(ConfigurableLocalSessionFactoryBean) { bean ->
      bean.autowire = 'byName'       // Autowiring behaviour. The other option is 'byType'. [autowire]
      bean.initMethod = 'init'       // Sets the initialisation method to 'init'. [init-method]
      bean.destroyMethod = 'destroy' // Sets the destruction method to 'destroy'. [destroy-method]
      bean.scope = 'request'         // Sets the scope of the bean. [scope]
      dataSource = dataSource
      hibernateProperties = [ "hibernate.hbm2ddl.auto":"create-drop",
                              "hibernate.show_sql":true  ]
  }

The strings in square brackets are the names of the equivalent bean attributes in Spring's XML definition.

h4. Using Constructor Arguments

Constructor arguments can be defined using parameters to each method that reside between the class of the bean and the last closure: 

bb.beans {
      exampleBean(MyExampleBean, "firstArgument", 2) {
          someProperty = [1,2,3]
      }
  }

h4. Configuring the BeanDefinition (Using factory methods)

The first argument to the closure is a reference to the bean configuration instance, which you can use to configure factory methods and invoke any method on the AbstractBeanDefinition class:

bb.beans {
      exampleBean(MyExampleBean) { bean ->
          bean.factoryMethod = "getInstance"
          bean.singleton = false
          someProperty = [1,2,3]
      }
  }

As an alternative you can also use the return value of the bean defining method to configure the bean:

bb.beans {
      def example = exampleBean(MyExampleBean) {
          someProperty = [1,2,3]
      }
      example.factoryMethod = "getInstance"
  }

h4. Using Factory beans

Spring defines the concept of factory beans and often a bean is created not from a class, but from one of these factories. In this case the bean has no class and instead you must pass the name of the factory bean to the bean:

bb.beans {
      myFactory(ExampleFactoryBean) {
          someProperty = [1,2,3]
      }
      myBean(myFactory) {
          name = "blah"
      }
  }

Note in the example above instead of a class we pass a reference to the myFactory bean into the bean defining method. Another common task is provide the name of the factory method to call on the factory bean. This can be done using Groovy's named parameter syntax:

bb.beans {
      myFactory(ExampleFactoryBean) {
          someProperty = [1,2,3]
      }
      myBean(myFactory:"getInstance") {
          name = "blah"
      }
  }

Here the getInstance method on the ExampleFactoryBean bean will be called in order to create the myBean bean.

h4. Creating Bean References at Runtime

Sometimes you don't know the name of the bean to be created until runtime. In this case you can use a string interpolation to invoke a bean defining method dynamically:

def beanName = "example"
  bb.beans {
      "${beanName}Bean"(MyExampleBean) {
          someProperty = [1,2,3]
      }
  }

In this case the beanName variable defined earlier is used when invoking a bean defining method.

Furthermore, because sometimes bean names are not known until runtime you may need to reference them by name when wiring together other beans. In this case using the ref method:

def beanName = "example"
  bb.beans {
      "${beanName}Bean"(MyExampleBean) {
          someProperty = [1,2,3]
      }
      anotherBean(AnotherBean) {
          example = ref("${beanName}Bean")
      }
  }

Here the example property of AnotherBean is set using a runtime reference to the exampleBean. The ref method can also be used to refer to beans from a parent ApplicationContext that is provided in the constructor of the BeanBuilder:

ApplicationContext parent = ...//
  der bb = new BeanBuilder(parent)
  bb.beans {
      anotherBean(AnotherBean) {
          example = ref("${beanName}Bean", true)
      }
  }

Here the second parameter true specifies that the reference will look for the bean in the parent context.

h4. Using Anonymous (Inner) Beans

You can use anonymous inner beans by setting a property of the bean to a block that takes an argument that is the bean type:

bb.beans {
      marge(Person.class) {
          name = "marge"
          husband =  { Person p ->
              name = "homer"
              age = 45
              props = [overweight:true, height:"1.8m"]
          }
          children = [bart, lisa]
      }
      bart(Person) {
          name = "Bart"
          age = 11
      }
      lisa(Person) {
          name = "Lisa"
          age = 9
      }
  }

In the above example we set the marge bean's husband property to a block that creates an inner bean reference. Alternatively if you have a factory bean you can ommit the type and just use passed bean definition instead to setup the factory:

bb.beans {
      personFactory(PersonFactory.class)
      marge(Person.class) {
          name = "marge"
          husband =  { bean ->
              bean.factoryBean = "personFactory"
              bean.factoryMethod = "newInstance"
              name = "homer"
              age = 45
              props = [overweight:true, height:"1.8m"]
          }
          children = [bart, lisa]
      }
  }

h4. Abstract Beans and Parent Bean Definitions

To create an abstract bean definition define a bean that takes no class:

class HolyGrailQuest {
      def start() { println "lets begin" }
  }
  class KnightOfTheRoundTable {
      String name
      String leader
      KnightOfTheRoundTable(String n) {
          this.name = n
      }
      HolyGrailQuest quest
      def embarkOnQuest() {
          quest.start()
      }
  }
  def bb = new grails.spring.BeanBuilder()
  bb.beans {
      abstractBean {
          leader = "Lancelot"
      }
      …
  }

Here we define an abstract bean that sets that has a leader property with the value of "Lancelot". Now to use the abstract bean set it as the parent of the child bean:

bb.beans {
      …
      quest(HolyGrailQuest)
      knights(KnightOfTheRoundTable, "Camelot") { bean ->
          bean.parent = abstractBean
          quest = quest
      }
  }

When using a parent bean you must set the parent property of the bean before setting any other properties on the bean!

If you want an abstract bean that has a class you can do it this way:

def bb = new grails.spring.BeanBuilder()
  bb.beans {
      abstractBean(KnightOfTheRoundTable) { bean ->
          bean.'abstract' = true
          leader = "Lancelot"
      }
      quest(HolyGrailQuest)
      knights("Camelot") { bean ->
          bean.parent = abstractBean
          quest = quest
      }
  }

In the above example we create an abstract bean of type KnightOfTheRoundTable and use the bean argument to set it to abstract. Later we define a knights bean that has no class, but inherits the class from the parent bean.

h4. Adding Variables to the Binding (Context)

If you're loading beans from a script you can set the binding to use by creating a Groovy Binding object:

def binding = new Binding()
  binding.foo = "bar"
  def bb = new BeanBuilder()
  bb.binding = binding
  bb.loadBeans("classpath:*SpringBeans.groovy")
  def ctx = bb.createApplicationContext()

h4. Loading Bean Definitions from the File System

You can use the BeanBuilder class to load external Groovy scripts that define beans using the same path matching syntax defined here. Example:

def bb = new BeanBuilder()
  bb.loadBeans("classpath:*SpringBeans.groovy")
  def applicationContext = bb.createApplicationContext()

Here the BeanBuilder will load all Groovy files on the classpath ending with SpringBeans.groovy and parse them into bean definitions. An example script can be seen below:

beans = {
      dataSource(BasicDataSource) {
          driverClassName = "org.hsqldb.jdbcDriver"
          url = "jdbc:hsqldb:mem:grailsDB"
          username = "sa"
          password = ""
      }
      sessionFactory(ConfigurableLocalSessionFactoryBean) {
          dataSource = dataSource
          hibernateProperties = [ "hibernate.hbm2ddl.auto":"create-drop",
                                  "hibernate.show_sql":true  ]
      }
  }

14.4 Property Placeholder Configuration

Grails supports the notion of property placeholder configuration through an extended version of Spring's PropertyPlaceholderConfigurer, which is typically useful when used in combination with externalized configuration.

Settings defined in either ConfigSlurper scripts of Java properties files can be used as placeholder values for Spring configuration in grails-app/conf/spring/resources.xml. For example given the following entries in grails-app/conf/Config.groovy (or an externalized config):

database.driver="com.mysql.jdbc.Driver"
database.dbname="mysql:mydb"

You can then specify placeholders in resources.xml as follows using the familiar ${..} syntax:

<bean id="dataSource" class="org.springframework.jdbc.datasource.DriverManagerDataSource">
   <property name="driverClassName"><value>${database.driver}</value></property>
   <property name="url"><value>jdbc:${database.dbname}</value></property>
 </bean>

14.5 Property Override Configuration

Grails supports the notion of property override configuration through an extended version of Spring's PropertyOverrideConfigurer, which is often useful when used in combination with externalized configuration.

Essentially you can supply ConfigSlurper scripts that define a beans block that can override settings on a bean:

beans {
   bookService.webServiceURL = "http://www.amazon.com"
}

The overrides are applied before the Spring ApplicationContext is constructed. The format is:

[bean name].[property name] = [value]

You can also provide a regular Java properties file with each entry prefixed with beans:

beans.bookService.webServiceURL=http://www.amazon.com